home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / basic / vbhelp.exe / HELPDEMO.TXT < prev    next >
Text File  |  1992-08-19  |  18KB  |  508 lines
  1. .TOPIC:
  2. Contents
  3. The Visual Basic for MS-DOS Help Toolkit makes it easy to add
  4. hypertext Help to your applications.  The text you are reading
  5. now is a Helpfile.  The Help Toolkit is written entirely in
  6. Visual Basic and can be modified.  Help files are standard ASCII
  7. files that can be edited with most text editors and even by
  8. Visual Basic itself.
  9.  
  10. Click the mouse over one of the topics below for more
  11. information.  Or press TAB to select a topic then press ENTER
  12. to jump to it.
  13.  
  14. Creating and Editing Help files
  15. Adding Help to Your Applications
  16. Using Help
  17. Customizing the Help Toolkit
  18. .TOPIC:
  19. Creating and Editing Help Files
  20. To create a new Help file:
  21.  
  22. 1.  Determine which topics a user might want Help with.
  23. 2.  Start any text editor that reads and writes ASCII files.
  24. 3.  Create a topic named Contents and type a table of
  25.     contents below.  See Creating and Editing Topics.
  26.     Note that the Contents command button will not work
  27.     correctly unless you include a topic named Contents.
  28. 4.  Every entry in the table of contents should be a link
  29.     to a Help topic.  See Creating Links
  30. 5.  Create a Help topic for every link in the table of
  31.     contents.  See Creating and Editing Topics
  32. 6.  Every Help topic can contain links to other Help topics.
  33. 7.  Help topics do not need to be listed in the table of
  34.     contents.
  35.  
  36. To edit an existing Help file:
  37. NOTE:  The Help Toolkit cannot access Microsoft .HLP files.
  38.  
  39. 1.  Open the Help file in a text editor that reads and writes
  40.     ASCII files.
  41. 2.  Modify Links and Topics as described above.
  42.  
  43. See Example Help File
  44. .TOPIC:
  45. Creating and Editing Topics
  46. The Help Toolkit distinguishes Help topics from ordinary
  47. text by requiring that all topics are formatted in a
  48. specific way.
  49.  
  50. 1.  The word TOPIC must be on a line by itself, preceeded
  51.     by a period (.) and followed by a colon (:).  TOPIC
  52.     must be in uppercase.
  53. 2.  The period must be the first character on the line.
  54. 3.  Only spaces are allowed after the colon.
  55. 4.  The name of the topic itself must be on the line
  56.     immediately below the .TOPIC: statement.
  57. 5.  The topic text should begin on the line after the
  58.     name of the topic.
  59. 6.  The Help Toolkit will not word wrap text.  Use the
  60.     ENTER key to break text into reasonable length lines.
  61.     64 character lines work well because the Help window
  62.     defaults to 66 characters wide.
  63. 7.  The next topic should begin immediately after the last
  64.     line of the current topic.
  65.  
  66. For example, the following would be a valid topic except
  67. that the period is the second character on the line not the
  68. first.
  69.  
  70.  .TOPIC:
  71. This is a help topic name
  72. This is the first line a Help topic.
  73. .
  74. .
  75. .
  76. .
  77. This is the last line of a Help topic.
  78.  
  79. See Creating Links   Example Help File
  80. .TOPIC:
  81. Creating Links
  82. Links are hot spots that a Help user clicks on to jump
  83. to a Help topic.  Links are ordinary text surrounded by
  84. special triangle characters (ASCII codes 16 and 17).
  85.  
  86. Links and Topics must have exactly the same name or the
  87. Help Toolkit will not be able to find a Topic when a Link
  88. is clicked.
  89.  
  90. For example, click on Valid Help Topic to see how Links
  91. jump to new Topics.  And click on Invalid Help Topic to
  92. see what happens if you create a Link without a matching
  93. Topic.
  94.  
  95. See Creating and Editing Topics
  96. .TOPIC:
  97. Adding Help to Your Applications
  98. Necessary Files
  99. ---------------
  100. You must add the following files to your project to use
  101. the Help Toolkit:
  102.  
  103. 1.  HELP.BAS
  104. 2.  HELPF.FRM
  105. 3.  HELPUTIL.FRM
  106.  
  107. All files that call Help Toolkit routines must also have
  108. the following statement at the module level:
  109.  
  110. '$INCLUDE: 'HELP.BI'
  111.  
  112. Calling Help Toolkit Routines
  113. -----------------------------
  114. Required Steps:
  115.  
  116. 1.  Initialize the Help system by calling the
  117. HelpRegister <HelpFileName$> procedure.  You should do this
  118. when your application starts.
  119.  
  120. 2.  Display Help topics or the table of contents by
  121. calling HelpShowTopic <HelpTopicName$>.  HelpTopicName$
  122. should be "Contents" to show the table of contents.
  123.  
  124. 3.  Call HelpClose just before your application ends.
  125. NOTE:  You must call HelpClose during a Form_Unload
  126. event if your application ends when the last form is
  127. closed rather than by executing an END statement.
  128. Your application will not end if you fail to do this
  129. because frmHelpMain is still LOADED although invisible.
  130.  
  131. Optional:
  132. 1.  Call HelpSetOptions to set Help colors and show/hide
  133. specific Help command buttons after you call HelpRegister.
  134. See Help Toolkit Procedures for details.
  135.  
  136. 2.  Call HelpSearch to open Help's Search dialog.  Many
  137. applications have a Search item under their Help menu.
  138.  
  139. See Example Help Toolkit Application and
  140.     Help Toolkit Procedures for detailed information.
  141. .TOPIC:
  142. Valid Help Topic
  143. You jumped to this topic by clicking the Valid Help Topic
  144. link.
  145.  
  146. Click ---> Creating Links or choose the Back command button
  147. to return.
  148. .TOPIC:
  149. Customizing the Help Toolkit
  150. You can add or remove functionality from the Help Toolkit
  151. by changing the code in the following files:
  152.  
  153. 1.  HELP.BAS
  154. 2.  HELPF.FRM
  155. 3.  HELPUTIL.FRM
  156.  
  157. HELP.BAS contains all the application callable procedures
  158. such as HelpShowTopic and HelpRegister.
  159.  
  160. HELPF.FRM is the main Help form.  It contains the code
  161. required to display and scroll through Help topics.  It
  162. also has the code used to detect mouse clicks (to jump Links)
  163. and keyboard support.
  164.  
  165. HELPUTIL.FRM is a form that serves as the Search dialog, the
  166. History dialog, and the Copy dialog.  It is called from
  167. HELPF.FRM and HELP.BAS.  The look of the form is controlled
  168. entirely from the cmdButtonBar_Click routine in HELPF.FRM and
  169. the HelpSearch routine in HELP.BAS.
  170.  
  171. HELPF.FRM and HELP.BAS use the HELP.BI INCLUDE file.
  172.  
  173. See Adding Help to Your Applications
  174. .TOPIC:
  175. Example Help File
  176. The following is an example of a small Help file.  Note that
  177. real Help files must be flush left.  This example is indented
  178. one character to stop the Help Toolkit from processing .TOPIC:
  179. statements.  A real Help file would also have ASCII 16 and 17
  180. characters in place of the > and < symbols used below.
  181.  
  182.  .TOPIC:
  183.  Contents
  184.  Welcome to Bob's Accounting System version 7.1
  185.  
  186.  <Introduction>
  187.  <Adding New Accounts>
  188.  <Ordering Additional Modules>
  189.  .TOPIC:
  190.  Introduction
  191.  Bob's Accounting System is specificially designed for small
  192.  business accounting.  It includes modules for <Accounts Payable>
  193.  and <Accounts Receivable>.  Other modules may be purchased
  194.  seperately.  See <Ordering Additional Modules>
  195.  .TOPIC:
  196.  Adding New Accounts
  197.  Choose New from the Accounts menu.
  198.  You can also press F8.
  199.  
  200.  Note that Bob's Accounting System can store as many accounts
  201.  as disk space allows.
  202.  .TOPIC:
  203.  Accounts Payable
  204.  Access the A/P module through the Payables menu.
  205.  
  206.  Note that A/P entries are automatially added to the general
  207.  ledger when you exit Bob's Accounting System.
  208.  
  209.  See <Accounts Receivable>
  210.  .TOPIC:
  211.  Accounts Receivable
  212.  Access the A/P module through the Receievables menu.
  213.  
  214.  Note that A/R entries are automatially added to the general
  215.  ledger when you exit Bob's Accounting System.
  216.  
  217.  See <Accounts Payable>
  218.  .TOPIC:
  219.  Ordering Additional Modules
  220.  You can call (123) 555-5555 between 9 am and 5 pm to
  221.  inquire about new modules.  New modules such as tax, benefits,
  222.  and inventory are scheduled to be ready later this year.
  223.  
  224. See Creating and Editing Help files
  225. .TOPIC:
  226. Example Help Toolkit Application
  227. The following shows how the Help Toolkit procedures should be
  228. added to an application.  Assume the application is one form
  229. with menu controls for Help|Contents, Help|Search, and
  230. Help|Using Help.  It also has a Text control named txtFileName
  231. and a check box named ckReadOnly.
  232.  
  233. ' Module-level
  234. '$INCLUDE: 'HELP.BI'
  235. DIM SHARED HelpLoaded%
  236.  
  237. SUB Form_Load ()
  238.     HelpRegister "MYHELP.TXT" , HelpLoaded%
  239.  
  240.     ' HelpLoaded% is set to TRUE (-1) if HelpRegister
  241.     ' was successful or to FALSE (0) if it failed.
  242.     IF HelpLoaded% = FALSE THEN
  243.         ' Ensure that Help menu choices cannot
  244.         ' be selected.
  245.         mnuHelpContents.Enable